// 版权所有2009 Go作者。版权所有。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// Malloc评测。
// 模仿tcmalloc的算法；较短的代码。

package runtime

import (
	"runtime/internal/atomic"
	"unsafe"
)

// 注意（rsc）：如果争用成为问题，这里的所有东西都可以使用cas。
var proflock mutex

// 所有内存分配都是本地的，不会从探查器外部转义。
// 禁止探查器引用垃圾收集的内存。

const (
	// 配置文件类型
	memProfile bucketType = 1 + iota
	blockProfile
	mutexProfile

	// bucket哈希表的大小
	buckHashSize = 179999

	// 要在bucket中记录的最大堆栈深度
	maxStack = 32
)

type bucketType int

// 一个bucket保存每个调用堆栈的配置文件信息。
// 表示形式有点低级，继承自C。
// 此结构定义了桶头。它在
// 内存中后跟堆栈字，然后是实际记录
// 数据，可以是memRecord，也可以是blockRecord。
// 
// 每个调用堆栈评测信息。
// 通过将调用堆栈散列到链表散列表中进行查找。
// 
// 没有堆指针。
// 
// go:notinheap 
type bucket struct {
	next    *bucket
	allnext *bucket
	typ     bucketType // memBucket或blockBucket（包括互斥文件）
	hash    uintptr
	size    uintptr
	nstk    uintptr
}

// memRecord是memProfile类型的bucket的bucket数据，
// 是内存配置文件的一部分。
type memRecord struct {
	// 需要以下复杂的三阶段统计累积方案
	// 才能获得一幅mallocs的一致图片，并在某个时间点释放
	// 数据。
	// 问题是malloc是实时出现的，而frees 
	// 仅在并发扫描期间在GC之后出现。因此，如果我们天真地计算它们，我们就会倾向于马洛斯。
	// 
	// 因此，我们延迟信息以获得一致的快照，就像标记终止的
	// 一样。分配计数到下一个标记
	// 终止的快照，当扫描释放计数到
	// /上一个标记终止的快照：
	// /
	// /MT MT MT 
	// /.·|·········································
	// /.·˙·······························································→ ▲ ← 免费
	// ┠┅┅┅┅┅┅┅┅┅┅┅P 
	// C+2→    C+1→  C 
	// 
	// alloc→ ▲ ← 免费
	// ┠┅┅┅┅┅┅┅┅┅┅┅P 
	// C+2→    C+1→  C 
	// 
	// 由于我们无法发布一致的快照，直到所有
	// 清除的空闲数据都被计算在内，所以我们会等到下一个
	// 标记终止（“上面的MT”）才发布上一个标记
	// 终止的快照（“上面的P”）。为此，分配
	// 和空闲事件将计入*future*堆配置文件
	// 循环（“上面的C+n”），并且我们只在必须完成该循环中所有
	// 事件后发布一个循环。具体来说：
	// 
	// Mallocs计入周期C+2。
	// 显式释放计入循环C+2。
	// GC释放（清扫期间完成）计入循环C+1。
	// 
	// 标记终止后，我们增加全局堆
	// 配置文件周期计数器，并将周期C 
	// 中的统计数据累积到活动配置文件中。

	// 活动是当前发布的配置文件。一个分析
	// 循环完成后，可以将其累积到活动中。
	active memRecordCycle

	// future记录我们正在统计的尚未发布的周期
	// 的配置文件事件。这是由全局堆配置文件循环C索引的环形缓冲区
	// 并存储
	// 循环C、C+1和C+2。与现行计数不同，这些计数仅为单个周期的
	// 计数；在
	// /周期中，它们不是累积的。
	// 
	// 我们在这里存储循环C，因为在
	// C成为活动循环和将其刷新为
	// 活动循环之间有一个窗口。
	future [3]memRecordCycle
}

// memRecordCycle 
type memRecordCycle struct {
	allocs, frees           uintptr
	alloc_bytes, free_bytes uintptr
}

// 将b累加到a中。它不是零b。
func (a *memRecordCycle) add(b *memRecordCycle) {
	a.allocs += b.allocs
	a.frees += b.frees
	a.alloc_bytes += b.alloc_bytes
	a.free_bytes += b.free_bytes
}

// blockRecord是blockProfile类型的bucket的bucket数据，
// 用于阻塞和互斥配置文件。
type blockRecord struct {
	count  float64
	cycles int64
}

var (
	mbuckets  *bucket // 内存配置文件存储桶
	bbuckets  *bucket // 阻塞配置文件存储桶
	xbuckets  *bucket // 互斥配置文件存储桶
	buckhash  *[179999]*bucket
	bucketmem uintptr

	mProf struct {
		// mProf中的所有字段都受proflock保护。

		// 循环是全局堆配置文件循环。这在mProfCycleWrap包装
		// 。
		cycle uint32
		// 已刷新表示所有存储桶中的未来[cycle]
		// 已刷新到活动配置文件。
		flushed bool
	}
)

const mProfCycleWrap = uint32(len(memRecord{}.future)) * (2 << 24)

// newBucket使用给定类型和数量的堆栈条目分配一个bucket。
func newBucket(typ bucketType, nstk int) *bucket {
	size := unsafe.Sizeof(bucket{}) + uintptr(nstk)*unsafe.Sizeof(uintptr(0))
	switch typ {
	default:
		throw("invalid profile bucket type")
	case memProfile:
		size += unsafe.Sizeof(memRecord{})
	case blockProfile, mutexProfile:
		size += unsafe.Sizeof(blockRecord{})
	}

	b := (*bucket)(persistentalloc(size, 0, &memstats.buckhash_sys))
	bucketmem += size
	b.typ = typ
	b.nstk = uintptr(nstk)
	return b
}

// stk返回保存堆栈的b中的切片。
func (b *bucket) stk() []uintptr {
	stk := (*[maxStack]uintptr)(add(unsafe.Pointer(b), unsafe.Sizeof(*b)))
	return stk[:b.nstk:b.nstk]
}

// mp返回与memProfile bucket b关联的memRecord。
func (b *bucket) mp() *memRecord {
	if b.typ != memProfile {
		throw("bad use of bucket.mp")
	}
	data := add(unsafe.Pointer(b), unsafe.Sizeof(*b)+b.nstk*unsafe.Sizeof(uintptr(0)))
	return (*memRecord)(data)
}

// bp返回与blockProfile bucket b关联的blockRecord。
func (b *bucket) bp() *blockRecord {
	if b.typ != blockProfile && b.typ != mutexProfile {
		throw("bad use of bucket.bp")
	}
	data := add(unsafe.Pointer(b), unsafe.Sizeof(*b)+b.nstk*unsafe.Sizeof(uintptr(0)))
	return (*blockRecord)(data)
}

// 返回stk[0:nstk]的bucket，需要时分配新bucket。
func stkbucket(typ bucketType, size uintptr, stk []uintptr, alloc bool) *bucket {
	if buckhash == nil {
		buckhash = (*[buckHashSize]*bucket)(sysAlloc(unsafe.Sizeof(*buckhash), &memstats.buckhash_sys))
		if buckhash == nil {
			throw("runtime: cannot allocate memory")
		}
	}

	// 哈希堆栈。
	var h uintptr
	for _, pc := range stk {
		h += pc
		h += h << 10
		h ^= h >> 6
	}
	// 大小为哈希的
	h += size
	h += h << 10
	h ^= h >> 6
	// 完成
	h += h << 3
	h ^= h >> 11

	i := int(h % buckHashSize)
	for b := buckhash[i]; b != nil; b = b.next {
		if b.typ == typ && b.hash == h && b.size == size && eqslice(b.stk(), stk) {
			return b
		}
	}

	if !alloc {
		return nil
	}

	// 创建新桶。
	b := newBucket(typ, len(stk))
	copy(b.stk(), stk)
	b.hash = h
	b.size = size
	b.next = buckhash[i]
	buckhash[i] = b
	if typ == memProfile {
		b.allnext = mbuckets
		mbuckets = b
	} else if typ == mutexProfile {
		b.allnext = xbuckets
		xbuckets = b
	} else {
		b.allnext = bbuckets
		bbuckets = b
	}
	return b
}

func eqslice(x, y []uintptr) bool {
	if len(x) != len(y) {
		return false
	}
	for i, xi := range x {
		if xi != y[i] {
			return false
		}
	}
	return true
}

// mProf_NextCycle发布下一个堆配置文件周期，并创建一个
// fresh堆配置文件周期。此操作速度快，可在STW期间通过
// 完成。在再次调用
// mProf\U NextCycle之前，调用者必须先调用mProf\U Flush。
// 
// 这是在STW期间通过标记终止调用的，因此分配和
// 在世界再次启动后释放将计入新的堆
// 分析周期。
func mProf_NextCycle() {
	lock(&proflock)
	// 我们显式地包装mProf.cycle，而不是依赖于
	// uint包装，因为memRecord.future环本身不以二的幂包装。
	mProf.cycle = (mProf.cycle + 1) % mProfCycleWrap
	mProf.flushed = false
	unlock(&proflock)
}

// mProf_Flush将当前堆配置文件中的事件刷新到活动配置文件中。在此之后，可以安全地使用mProf_NextCycle启动新的
// 堆分析周期。
// 
// 这是在标记终止启动世界后由GC调用的。在
// 与mProf_NextCycle相比，这有点贵，但安全的
// 可以同时进行。
func mProf_Flush() {
	lock(&proflock)
	if !mProf.flushed {
		mProf_FlushLocked()
		mProf.flushed = true
	}
	unlock(&proflock)
}

func mProf_FlushLocked() {
	c := mProf.cycle
	for b := mbuckets; b != nil; b = b.allnext {
		mp := b.mp()

		// 将循环C刷新到已发布的配置文件中，并清除
		// 以供重用。
		mpc := &mp.future[c%uint32(len(mp.future))]
		mp.active.add(mpc)
		*mpc = memRecordCycle{}
	}
}

// mProf_此GC循环的所有扫描可用记录已完成
// 。这会在最后一次标记终止时发布堆配置文件
// 快照，而不会提前堆
// 配置文件周期。
func mProf_PostSweep() {
	lock(&proflock)
	// 将循环C+1刷新到活动配置文件，以便从
	// 最后一个标记终止变得可见*不要*推进
	// 循环，因为我们仍然在累积
	// C+2循环中的allocs，它们必须在下一个标记终止
	// 中变成C+1，依此类推。
	c := mProf.cycle
	for b := mbuckets; b != nil; b = b.allnext {
		mp := b.mp()
		mpc := &mp.future[(c+1)%uint32(len(mp.future))]
		mp.active.add(mpc)
		*mpc = memRecordCycle{}
	}
	unlock(&proflock)
}

// 由malloc调用以记录一个分析的块。
func mProf_Malloc(p unsafe.Pointer, size uintptr) {
	var stk [maxStack]uintptr
	nstk := callers(4, stk[:])
	lock(&proflock)
	b := stkbucket(memProfile, size, stk[:nstk], true)
	c := mProf.cycle
	mp := b.mp()
	mpc := &mp.future[(c+2)%uint32(len(mp.future))]
	mpc.allocs++
	mpc.alloc_bytes += size
	unlock(&proflock)

	// Setprofilebucket锁定一组其他互斥锁，因此我们称之为proflock之外的互斥锁。
	// 这减少了潜在的争用和死锁的机会。
	// 因为在调用mProf_Malloc时对象必须是活动的，所以
	// 可以以非原子方式执行此操作。
	systemstack(func() {
		setprofilebucket(p, b)
	})
}

// 释放配置文件块时调用。
func mProf_Free(b *bucket, size uintptr) {
	lock(&proflock)
	c := mProf.cycle
	mp := b.mp()
	mpc := &mp.future[(c+1)%uint32(len(mp.future))]
	mpc.frees++
	mpc.free_bytes += size
	unlock(&proflock)
}

var blockprofilerate uint64 // 在CPU时钟中

// SetBlockProfileRate控制阻塞配置文件中报告的goroutine阻塞事件
// 的分数。探查器的目标是对
// /进行采样，平均每阻塞一个事件的速率为纳秒。
// 
// 要在配置文件中包含每个阻塞事件，通过率=1。
// 要完全关闭评测，通过率<=0。
func SetBlockProfileRate(rate int) {
	var r int64
	if rate <= 0 {
		r = 0 // 禁用评测
	} else if rate == 1 {
		r = 1 // 评测一切
	} else {
		// 将ns转换为周期，使用float64防止乘法期间溢出
		r = int64(float64(rate) * float64(tickspersecond()) / (1000 * 1000 * 1000))
		if r == 0 {
			r = 1
		}
	}

	atomic.Store64(&blockprofilerate, uint64(r))
}

func blockevent(cycles int64, skip int) {
	if cycles <= 0 {
		cycles = 1
	}

	rate := int64(atomic.Load64(&blockprofilerate))
	if blocksampled(cycles, rate) {
		saveblockevent(cycles, rate, skip+1, blockProfile)
	}
}

// 对于周期>=速率的所有事件，blocksampled返回true。较短的
// 事件有一个周期/速率随机返回true的机会。
func blocksampled(cycles, rate int64) bool {
	if rate <= 0 || (rate > cycles && int64(fastrand())%rate > cycles) {
		return false
	}
	return true
}

func saveblockevent(cycles, rate int64, skip int, which bucketType) {
	gp := getg()
	var nstk int
	var stk [maxStack]uintptr
	if gp.m.curg == nil || gp.m.curg == gp {
		nstk = callers(skip, stk[:])
	} else {
		nstk = gcallers(gp.m.curg, skip, stk[:])
	}
	lock(&proflock)
	b := stkbucket(which, 0, stk[:nstk], true)

	if which == blockProfile && cycles < rate {
		// 消除采样偏差，请参阅http:
		b.bp().count += float64(rate) / float64(cycles)
		b.bp().cycles += rate
	} else {
		b.bp().count++
		b.bp().cycles += cycles
	}
	unlock(&proflock)
}

var mutexprofilerate uint64 // 分数采样

// SetMutexProfileFraction控制互斥配置文件中报告的互斥争用事件
// 的分数。平均1/次事件被
// 报告。返回以前的速率。
// 
// 要完全关闭评测，通过率为0。
// 仅读取当前速率，通过率<0。
// （对于n>1，采样的详细信息可能会更改。）
func SetMutexProfileFraction(rate int) int {
	if rate < 0 {
		return int(mutexprofilerate)
	}
	old := mutexprofilerate
	atomic.Store64(&mutexprofilerate, uint64(rate))
	return int(old)
}

// go:linkname mutexevent sync.event 
func mutexevent(cycles int64, skip int) {
	if cycles < 0 {
		cycles = 0
	}
	rate := int64(atomic.Load64(&mutexprofilerate))
	// /TODO（pjw）：测量始终调用fastrand与使用某些
	// like malloc.go:nextSample（）
	if rate > 0 && int64(fastrand())%rate == 0 {
		saveblockevent(cycles, rate, skip+1, mutexProfile)
	}
}

// /go配置文件数据接口。

// 堆栈记录描述单个执行堆栈。
type StackRecord struct {
	Stack0 [32]uintptr // 此记录的堆栈跟踪；结束于第一个0条目
}

// 堆栈返回与记录关联的堆栈跟踪，
// 前缀为r.Stack0。
func (r *StackRecord) Stack() []uintptr {
	for i, v := range r.Stack0 {
		if v == 0 {
			return r.Stack0[0:i]
		}
	}
	return r.Stack0[0:]
}

// MemProfileRate控制内存配置文件中记录和报告的内存分配比例。
// 探查器的目标是对平均分配的
// 每分配一个MemProfileRate字节进行采样。
// 
// 要在配置文件中包含每个分配的块，请将MemProfileRate设置为1。
// 若要完全关闭评测，请将MemProfileRate设置为0。
// 
// 处理内存配置文件的工具假定
// 配置文件速率在程序的整个生命周期内是恒定的，并且等于当前值。更改
// 内存分析速率的程序应该只更改一次，最早在程序执行过程中更改
// 内存分析速率（例如，在main的开头更改
// 内存分析速率）。
var MemProfileRate int = defaultMemProfileRate(512 * 1024)

// 如果设置了disableMemoryProfiling，则defaultMemProfileRate返回0。
// 它主要用于上面的MemProfileRate 
// 的godoc呈现。
func defaultMemProfileRate(v int) int {
	if disableMemoryProfiling {
		return 0
	}
	return v
}

// 如果未使用runtime.MemProfile 
// 并且链接类型保证其他人不能在其他地方使用它，则链接器将设置disableMemoryProfiling。
var disableMemoryProfiling bool

// MemProfileRecord描述通过特定调用序列（堆栈跟踪）分配的活动对象。
type MemProfileRecord struct {
	AllocBytes, FreeBytes     int64       // 分配的字节数，释放的
	AllocObjects, FreeObjects int64       // 分配的对象数，释放的
	Stack0                    [32]uintptr // 此记录的堆栈跟踪；结束于第一个0条目
}

// InUseBytes返回正在使用的字节数（AllocBytes-FreeBytes）。
func (r *MemProfileRecord) InUseBytes() int64 { return r.AllocBytes - r.FreeBytes }

// InUseObjects返回正在使用的对象数（AllocObjects-FreeObjects）。
func (r *MemProfileRecord) InUseObjects() int64 {
	return r.AllocObjects - r.FreeObjects
}

// 堆栈返回与记录关联的堆栈跟踪，
// 前缀为r.Stack0。
func (r *MemProfileRecord) Stack() []uintptr {
	for i, v := range r.Stack0 {
		if v == 0 {
			return r.Stack0[0:i]
		}
	}
	return r.Stack0[0:]
}

// MemProfile返回每个分配分配和释放的内存的配置文件
// 站点。
// 
// MemProfile返回n，当前内存配置文件中的记录数。
// 如果len（p）>=n，MemProfile将配置文件复制到p并返回n，true。
// 如果len（p）<n，MemProfile不改变p并返回n，false。
// 
// 如果inuseZero为true，则配置文件包含分配记录
// 其中r.AllocBytes>0，但r.AllocBytes==r.FreeBytes。
// 这些是分配内存的站点，但所有
// 都已释放回运行时。
// 
// 返回的配置文件最多可能有两个垃圾收集周期。
// 这是为了避免配置文件偏向分配；由于
// 分配是实时进行的，但释放会延迟到垃圾
// 收集器执行清理为止，因此配置文件仅说明有可能被垃圾收集器释放的分配
// 的情况。
// 
// 大多数客户端都应该使用runtime/pprof包或
// 测试包的-test.memprofile标志，而不是直接调用memprofile的
// 。
func MemProfile(p []MemProfileRecord, inuseZero bool) (n int, ok bool) {
	lock(&proflock)
	// 如果我们处于mProf_下一个周期和mProf_刷新之间，请注意
	// 刷新活动配置文件，因此我们只需查看下面的活动配置文件。
	mProf_FlushLocked()
	clear := true
	for b := mbuckets; b != nil; b = b.allnext {
		mp := b.mp()
		if inuseZero || mp.active.alloc_bytes != mp.active.free_bytes {
			n++
		}
		if mp.active.allocs != 0 || mp.active.frees != 0 {
			clear = false
		}
	}
	if clear {
		// 绝对没有数据，表明垃圾回收
		// 尚未发生。为了允许在
		// 从执行开始就禁用垃圾收集时进行分析，
		// 累积所有周期，并重新计算存储桶。
		n = 0
		for b := mbuckets; b != nil; b = b.allnext {
			mp := b.mp()
			for c := range mp.future {
				mp.active.add(&mp.future[c])
				mp.future[c] = memRecordCycle{}
			}
			if inuseZero || mp.active.alloc_bytes != mp.active.free_bytes {
				n++
			}
		}
	}
	if n <= len(p) {
		ok = true
		idx := 0
		for b := mbuckets; b != nil; b = b.allnext {
			mp := b.mp()
			if inuseZero || mp.active.alloc_bytes != mp.active.free_bytes {
				record(&p[idx], b)
				idx++
			}
		}
	}
	unlock(&proflock)
	return
}

// 将b的数据写入r。
func record(r *MemProfileRecord, b *bucket) {
	mp := b.mp()
	r.AllocBytes = int64(mp.active.alloc_bytes)
	r.FreeBytes = int64(mp.active.free_bytes)
	r.AllocObjects = int64(mp.active.allocs)
	r.FreeObjects = int64(mp.active.frees)
	if raceenabled {
		racewriterangepc(unsafe.Pointer(&r.Stack0[0]), unsafe.Sizeof(r.Stack0), getcallerpc(), funcPC(MemProfile))
	}
	if msanenabled {
		msanwrite(unsafe.Pointer(&r.Stack0[0]), unsafe.Sizeof(r.Stack0))
	}
	copy(r.Stack0[:], b.stk())
	for i := int(b.nstk); i < len(r.Stack0); i++ {
		r.Stack0[i] = 0
	}
}

func iterate_memprof(fn func(*bucket, uintptr, *uintptr, uintptr, uintptr, uintptr)) {
	lock(&proflock)
	for b := mbuckets; b != nil; b = b.allnext {
		mp := b.mp()
		fn(b, b.nstk, &b.stk()[0], b.size, mp.active.allocs, mp.active.frees)
	}
	unlock(&proflock)
}

// BlockProfileRecord描述了在特定调用序列（堆栈跟踪）上产生的阻塞事件。
type BlockProfileRecord struct {
	Count  int64
	Cycles int64
	StackRecord
}

// BlockProfile返回n，当前块配置文件中的记录数。
// 如果len（p）>=n，BlockProfile将配置文件复制到p并返回n，true。
// 如果len（p）<n，则BlockProfile不会更改p并返回n，false。
// 
// 大多数客户端都应该使用runtime/pprof包或
// 测试包的-test.blockprofile标志，而不是直接调用blockprofile的
// 。
func BlockProfile(p []BlockProfileRecord) (n int, ok bool) {
	lock(&proflock)
	for b := bbuckets; b != nil; b = b.allnext {
		n++
	}
	if n <= len(p) {
		ok = true
		for b := bbuckets; b != nil; b = b.allnext {
			bp := b.bp()
			r := &p[0]
			r.Count = int64(bp.count)
			// 避免呼叫者担心被零除的错误。
			// 请参阅http:
			if r.Count == 0 {
				r.Count = 1
			}
			r.Cycles = bp.cycles
			if raceenabled {
				racewriterangepc(unsafe.Pointer(&r.Stack0[0]), unsafe.Sizeof(r.Stack0), getcallerpc(), funcPC(BlockProfile))
			}
			if msanenabled {
				msanwrite(unsafe.Pointer(&r.Stack0[0]), unsafe.Sizeof(r.Stack0))
			}
			i := copy(r.Stack0[:], b.stk())
			for ; i < len(r.Stack0); i++ {
				r.Stack0[i] = 0
			}
			p = p[1:]
		}
	}
	unlock(&proflock)
	return
}

// MutexProfile返回n，即当前互斥配置文件中的记录数。
// 如果len（p）>=n，则MutexProfile将配置文件复制到p并返回n，true。
// 否则，MutexProfile不会更改p，并返回n，false。
// 
// 大多数客户端应该使用runtime/pprof包
// 而不是直接调用MutexProfile。
func MutexProfile(p []BlockProfileRecord) (n int, ok bool) {
	lock(&proflock)
	for b := xbuckets; b != nil; b = b.allnext {
		n++
	}
	if n <= len(p) {
		ok = true
		for b := xbuckets; b != nil; b = b.allnext {
			bp := b.bp()
			r := &p[0]
			r.Count = int64(bp.count)
			r.Cycles = bp.cycles
			i := copy(r.Stack0[:], b.stk())
			for ; i < len(r.Stack0); i++ {
				r.Stack0[i] = 0
			}
			p = p[1:]
		}
	}
	unlock(&proflock)
	return
}

// ThreadCreateProfile返回n，线程创建配置文件中的记录数。
// 如果len（p）>=n，则ThreadCreateProfile将配置文件复制到p并返回n，true。
// 如果len（p）<n，则ThreadCreateProfile不会更改p并返回n，false。
// 
// 大多数客户端应该使用runtime/pprof包，而不是直接调用ThreadCreateProfile的
// 包。
func ThreadCreateProfile(p []StackRecord) (n int, ok bool) {
	first := (*m)(atomic.Loadp(unsafe.Pointer(&allm)))
	for mp := first; mp != nil; mp = mp.alllink {
		n++
	}
	if n <= len(p) {
		ok = true
		i := 0
		for mp := first; mp != nil; mp = mp.alllink {
			p[i].Stack0 = mp.createstack
			i++
		}
	}
	return
}

// go:linkname runtime\u goroutineProfileWithLabels runtime/pprof.runtime\u goroutineProfileWithLabels 
func runtime_goroutineProfileWithLabels(p []StackRecord, labels []unsafe.Pointer) (n int, ok bool) {
	return goroutineProfileWithLabels(p, labels)
}

// 标签可能为零。如果标签为非nil，则其长度必须与p相同。
func goroutineProfileWithLabels(p []StackRecord, labels []unsafe.Pointer) (n int, ok bool) {
	if labels != nil && len(labels) != len(p) {
		labels = nil
	}
	gp := getg()

	isOK := func(gp1 *g) bool {
		// 在此处检查isSystemGoroutine将使GoroutineProfile 
		// 与NumGoroutine和Stack一致。
		return gp1 != gp && readgstatus(gp1) != _Gdead && !isSystemGoroutine(gp1, false)
	}

	stopTheWorld("profile")

	// 世界已停止，无需锁定。
	n = 1
	forEachGRace(func(gp1 *g) {
		if isOK(gp1) {
			n++
		}
	})

	if n <= len(p) {
		ok = true
		r, lbl := p, labels

		// 保存当前goroutine。
		sp := getcallersp()
		pc := getcallerpc()
		systemstack(func() {
			saveg(pc, sp, gp, &r[0])
		})
		r = r[1:]

		// 如果我们有地方放置goroutine labelmap，请将其插入其中。
		if labels != nil {
			lbl[0] = gp.labels
			lbl = lbl[1:]
		}

		// 保存其他goroutine。
		forEachGRace(func(gp1 *g) {
			if !isOK(gp1) {
				return
			}

			if len(r) == 0 {
				// 应该是不可能的，但是返回一个
				// 截断的配置文件比使整个过程崩溃要好。
				return
			}
			saveg(^uintptr(0), ^uintptr(0), gp1, &r[0])
			if labels != nil {
				lbl[0] = gp1.labels
				lbl = lbl[1:]
			}
			r = r[1:]
		})
	}

	startTheWorld()
	return n, ok
}

// GoroutineProfile返回n，活动goroutine堆栈配置文件中的记录数。
// 如果len（p）>=n，则GoroutineProfile将配置文件复制到p并返回n，true。
// 如果len（p）<n，则GoroutineProfile不会更改p并返回n，false。
// 
// 大多数客户端应该使用runtime/pprof包，而不是直接调用GoroutineProfile的
// 包。
func GoroutineProfile(p []StackRecord) (n int, ok bool) {

	return goroutineProfileWithLabels(p, nil)
}

func saveg(pc, sp uintptr, gp *g, r *StackRecord) {
	n := gentraceback(pc, sp, 0, gp, 0, &r.Stack0[0], len(r.Stack0), nil, nil, 0)
	if n < len(r.Stack0) {
		r.Stack0[n] = 0
	}
}

// 堆栈将调用goroutine的堆栈跟踪格式化为buf 
// 并返回写入buf的字节数。
// 如果all为真，堆栈将所有其他goroutine的堆栈跟踪格式化为当前goroutine跟踪后的buf。
func Stack(buf []byte, all bool) int {
	if all {
		stopTheWorld("stack trace")
	}

	n := 0
	if len(buf) > 0 {
		gp := getg()
		sp := getcallersp()
		pc := getcallerpc()
		systemstack(func() {
			g0 := getg()
			// 强制回溯=1以覆盖GOTRACEBACK设置，
			// 以便堆栈的结果一致。
			// GOTRACEBACK只是关于崩溃转储。
			g0.m.traceback = 1
			g0.writebuf = buf[0:0:len(buf)]
			goroutineheader(gp)
			traceback(pc, sp, 0, gp)
			if all {
				tracebackothers(gp)
			}
			g0.m.traceback = 0
			n = len(g0.writebuf)
			g0.writebuf = nil
		})
	}

	if all {
		startTheWorld()
	}
	return n
}

// alloc/free/gc的跟踪。

var tracelock mutex

func tracealloc(p unsafe.Pointer, size uintptr, typ *_type) {
	lock(&tracelock)
	gp := getg()
	gp.m.traceback = 2
	if typ == nil {
		print("tracealloc(", p, ", ", hex(size), ")\n")
	} else {
		print("tracealloc(", p, ", ", hex(size), ", ", typ.string(), ")\n")
	}
	if gp.m.curg == nil || gp == gp.m.curg {
		goroutineheader(gp)
		pc := getcallerpc()
		sp := getcallersp()
		systemstack(func() {
			traceback(pc, sp, 0, gp)
		})
	} else {
		goroutineheader(gp.m.curg)
		traceback(^uintptr(0), ^uintptr(0), 0, gp.m.curg)
	}
	print("\n")
	gp.m.traceback = 0
	unlock(&tracelock)
}

func tracefree(p unsafe.Pointer, size uintptr) {
	lock(&tracelock)
	gp := getg()
	gp.m.traceback = 2
	print("tracefree(", p, ", ", hex(size), ")\n")
	goroutineheader(gp)
	pc := getcallerpc()
	sp := getcallersp()
	systemstack(func() {
		traceback(pc, sp, 0, gp)
	})
	print("\n")
	gp.m.traceback = 0
	unlock(&tracelock)
}

func tracegc() {
	lock(&tracelock)
	gp := getg()
	gp.m.traceback = 2
	print("tracegc()\n")
	// 运行在m->g0堆栈上；显示所有非g0 goroutines 
	tracebackothers(gp)
	print("end tracegc\n")
	print("\n")
	gp.m.traceback = 0
	unlock(&tracelock)
}
